﻿using BUGCOME.Infrastructure.Attribute;
using BUGCOME.Infrastructure.Model;
using BUGCOME.Model.Auth;
using BUGCOME.Model.Auth.dto;


namespace BUGCOME.Service.Auth.IServices
{



    /// <summary>
    /// 用户基础服务接口，定义用户基本信息管理的核心操作
    /// 继承自IBaseService，包含通用的CRUD方法
    /// </summary>
    /// <remarks>
    /// 该接口为用户基础信息管理提供服务契约，
    /// 通常包含对UserBase实体的查询、添加、更新和删除操作
    /// 
    /// 实现类应遵循以下规范：
    /// 1. 所有方法应保证数据一致性和事务完整性
    /// 2. 敏感操作（如删除）应进行权限校验
    /// 3. 涉及状态变更的操作应记录操作日志
    /// </remarks>

    public interface IUserBaseService : IBaseService<UserBase>
    {
        /// <summary>
        /// 检查手机号是否已被绑定，并返回绑定的用户ID列表
        /// </summary>
        /// <param name="phoneNum">待检查的手机号</param>
        /// <returns>
        /// 异步返回包含绑定用户ID的列表：
        /// - 空列表：手机号未被绑定
        /// - 包含单个元素：手机号被单个用户绑定
        /// - 包含多个元素：手机号被多个用户绑定（可能存在数据异常）
        /// </returns>
        Task<List<long>> CheckPhoneBindAsync(string phoneNum);

        /// <summary>
        /// 根据登录信息进行用户认证
        /// </summary>
        /// <param name="dto">包含用户名、密码等登录信息的DTO</param>
        /// <returns>认证成功返回用户实体，失败返回null</returns>
        /// <exception cref="CustomException">
        /// 可能抛出的异常：
        /// - 用户名不存在
        /// - 密码错误
        /// - 用户被禁用
        /// </exception>
        /// <remarks>
        /// 实现建议：
        /// 1. 密码校验应使用安全的哈希比较（如PBKDF2）
        /// 2. 登录失败应记录尝试次数，防止暴力破解
        /// 3. 登录成功应更新用户最后登录时间和IP
        /// </remarks>
        Task<UserBase> LoginAsync(LoginDto dto);

        /// <summary>
        /// 异步绑定用户手机号码
        /// </summary>
        /// <param name="uid">用户唯一标识符</param>
        /// <param name="phoneNum">待绑定的手机号码（需符合格式要求）</param>
      
        Task<long> PhoneBindAsync(long uid, string phoneNum);

        /// <summary>
        /// 更新用户的登录信息
        /// </summary>
        /// <param name="loginIP">用户登录的IP地址</param>
        /// <param name="userId">用户ID</param>
        /// <returns>表示异步操作的任务</returns>
        /// <exception cref="ArgumentException">当userId无效时抛出</exception>
        /// <remarks>
        /// 更新内容通常包括：
        /// - 最后登录IP
        /// - 最后登录时间
        /// - 登录次数累计
        /// </remarks>
        Task UpdateLoginInfoAsync(string loginIP, long userId);

        /// <summary>
        /// 异步注册新用户
        /// </summary>
        /// <param name="dto">注册信息数据传输对象</param>
        /// <returns>表示异步操作的任务，包含注册成功后的用户实体</returns>
        Task<ApiResult> RegisterAsync(RegisterDto dto);

        /// <summary>
        /// 异步重置指定用户的密码
        /// </summary>
        /// <param name="id">要重置密码的用户ID</param>
        /// <param name="pwd">新密码（需为已加密格式）</param>
        /// <returns>表示异步操作的任务，返回受影响的行数</returns>
        Task<long> ResetPwdAsync(long id, string pwd);

        /// <summary>
        /// 异步根据用户ID查询用户信息
        /// </summary>
        /// <param name="userid">要查询的用户唯一标识</param>
        /// <returns>表示异步操作的任务，包含查询到的用户基类对象</returns>
        Task<UserBase> SelectUserByIdAsync(long userid);
    }
}
